﻿#region COPYRIGHT
//--------------------------------------------------------------------------------
// <copyright file="noiseutils.cs" company="starLiGHT Entertainment Studios">
//    Copyright (c) 2007, 2008, 2009, 2010, 2011
//       Roland Rosenkranz (Glatzemann@email.de)
//
//    Based on libnoise by Jason Bevins
//      Copyright (C) 2003, 2004 Jason Bevins (licensed under LGPL)
// </copyright>
// <license>
//   This file is part of starLiGHT.Noise.
//
//   starLiGHT.Noise is free software: you can redistribute it and/or modify
//   it under the terms of the GNU Lesser General Public License as published by
//   the Free Software Foundation, either version 3 of the License, or
//   (at your option) any later version.
//
//   starLiGHT.Noise is distributed in the hope that it will be useful,
//   but WITHOUT ANY WARRANTY; without even the implied warranty of
//   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//   GNU Lesser General Public License for more details.
//
//   You should have received a copy of the GNU Lesser General Public License
//   along with starLiGHT.Noise. If not, see http://www.gnu.org/licenses/.
//    
//   ADDITIONAL (commercial) LICENSES for starLiGHT.Noise are available on request.
// </license>
// <version>
// **************[ starLiGHT.Engine SVN ]**********************
// * $Rev:: 7648                  $:  Revision of last commit *
// * $Author:: unknown            $:  Author of last commit   *
// * $Date:: 2011-03-26 19:11:26 #$:  Date of last commit     *
// ************************************************************
// </version>
//--------------------------------------------------------------------------------
#endregion

namespace starLiGHT.Noise.Noise
{
    #region Using Statements
    using System;
    using System.Collections.Generic;
    using System.Text;

    #endregion

    ///// Abstract base class for a noise-map builder
    /////
    ///// A builder class builds a noise map by filling it with coherent-noise
    ///// values generated from the surface of a three-dimensional mathematical
    ///// object.  Each builder class defines a specific three-dimensional
    ///// surface, such as a cylinder, sphere, or plane.
    /////
    ///// A builder class describes these input values using a coordinate system
    ///// applicable for the mathematical object (e.g., a latitude/longitude
    ///// coordinate system for the spherical noise-map builder.)  It then
    ///// "flattens" these coordinates onto a plane so that it can write the
    ///// coherent-noise values into a two-dimensional noise map.
    /////
    ///// <b>Building the Noise Map</b>
    /////
    ///// To build the noise map, perform the following steps:
    ///// - Pass the bounding coordinates to the SetBounds() method.
    ///// - Pass the noise map size, in points, to the SetDestSize() method.
    ///// - Pass a NoiseMap object to the SetDestNoiseMap() method.
    ///// - Pass a noise module (derived from noise::module::Module) to the
    /////   SetSourceModule() method.
    ///// - Call the Build() method.
    /////
    ///// You may also pass a callback function to the SetCallback() method.
    ///// The Build() method calls this callback function each time it fills a
    ///// row of the noise map with coherent-noise values.  This callback
    ///// function has a single integer parameter that contains a count of the
    ///// rows that have been completed.  It returns void.
    /////
    ///// Note that SetBounds() is not defined in the abstract base class; it is
    ///// only defined in the derived classes.  This is because each model uses
    ///// a different coordinate system.
    ////class NoiseMapBuilder
    ////{

    ////  public:

    ////    /// Constructor.
    ////    NoiseMapBuilder ();

    ////    /// Builds the noise map.
    ////   ///
    ////   /// @pre SetBounds() was previously called.
    ////   /// @pre SetDestNoiseMap() was previously called.
    ////   /// @pre SetSourceModule() was previously called.
    ////   /// @pre The width and height values specified by SetDestSize() are
    ////   /// positive.
    ////   /// @pre The width and height values specified by SetDestSize() do not
    ////   /// exceed the maximum possible width and height for the noise map.
    ////   ///
    ////   /// @post The original contents of the destination noise map is
    ////   /// destroyed.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   /// @throw noise::ExceptionOutOfMemory Out of memory.
    ////   ///
    ////   /// If this method is successful, the destination noise map contains
    ////   /// the coherent-noise values from the noise module specified by
    ////   /// SetSourceModule().
    ////   virtual void Build () = 0;

    ////   /// Returns the height of the destination noise map.
    ////   ///
    ////   /// @returns The height of the destination noise map, in points.
    ////   ///
    ////   /// This object does not change the height in the destination noise
    ////   /// map object until the Build() method is called.
    ////   double GetDestHeight () const
    ////   {
    ////     return this.destHeight;
    ////   }

    ////   /// Returns the width of the destination noise map.
    ////   ///
    ////   /// @returns The width of the destination noise map, in points.
    ////   ///
    ////   /// This object does not change the height in the destination noise
    ////   /// map object until the Build() method is called.
    ////   double GetDestWidth () const
    ////   {
    ////     return this.destWidth;
    ////   }

    ////   /// Sets the callback function that Build() calls each time it fills a
    ////   /// row of the noise map with coherent-noise values.
    ////   ///
    ////   /// @param pCallback The callback function.
    ////   ///
    ////   /// This callback function has a single integer parameter that
    ////   /// contains a count of the rows that have been completed.  It returns
    ////   /// void.  Pass a function with this signature to the SetCallback()
    ////   /// method.
    ////   void SetCallback (NoiseMapCallback pCallback);

    ////   /// Sets the destination noise map.
    ////   ///
    ////   /// @param destNoiseMap The destination noise map.
    ////   ///
    ////   /// The destination noise map will contain the coherent-noise values
    ////   /// from this noise map after a successful call to the Build() method.
    ////   ///
    ////   /// The destination noise map must exist throughout the lifetime of
    ////   /// this object unless another noise map replaces that noise map.
    ////   void SetDestNoiseMap (NoiseMap& destNoiseMap)
    ////   {
    ////     this.pDestNoiseMap = &destNoiseMap;
    ////   }

    ////   /// Sets the source module.
    ////   ///
    ////   /// @param sourceModule The source module.
    ////   ///
    ////   /// This object fills in a noise map with the coherent-noise values
    ////   /// from this source module.
    ////   ///
    ////   /// The source module must exist throughout the lifetime of this
    ////   /// object unless another noise module replaces that noise module.
    ////   void SetSourceModule (const module::Module& sourceModule)
    ////   {
    ////     this.pSourceModule = &sourceModule;
    ////   }

    ////   /// Sets the size of the destination noise map.
    ////   ///
    ////   /// @param destWidth The width of the destination noise map, in
    ////   /// points.
    ////   /// @param destHeight The height of the destination noise map, in
    ////   /// points.
    ////   ///
    ////   /// This method does not change the size of the destination noise map
    ////   /// until the Build() method is called.
    ////   void SetDestSize (int destWidth, int destHeight)
    ////   {
    ////     this.destWidth  = destWidth ;
    ////     this.destHeight = destHeight;
    ////   }

    //// protected:

    ////   /// The callback function that Build() calls each time it fills a row
    ////   /// of the noise map with coherent-noise values.
    ////   ///
    ////   /// This callback function has a single integer parameter that
    ////   /// contains a count of the rows that have been completed.  It returns
    ////   /// void.  Pass a function with this signature to the SetCallback()
    ////   /// method.
    ////   NoiseMapCallback this.pCallback;

    ////   /// Height of the destination noise map, in points.
    ////   int this.destHeight;

    ////   /// Width of the destination noise map, in points.
    ////   int this.destWidth;

    ////   /// Destination noise map that will contain the coherent-noise values.
    ////   NoiseMap* this.pDestNoiseMap;

    ////   /// Source noise module that will generate the coherent-noise values.
    ////   const module::Module* this.pSourceModule;

    ////};

    ///// Builds a cylindrical noise map.
    /////
    ///// This class builds a noise map by filling it with coherent-noise values
    ///// generated from the surface of a cylinder.
    /////
    ///// This class describes these input values using an (angle, height)
    ///// coordinate system.  After generating the coherent-noise value from the
    ///// input value, it then "flattens" these coordinates onto a plane so that
    ///// it can write the values into a two-dimensional noise map.
    /////
    ///// The cylinder model has a radius of 1.0 unit and has infinite height.
    ///// The cylinder is oriented along the @a y axis.  Its center is at the
    ///// origin.
    /////
    ///// The x coordinate in the noise map represents the angle around the
    ///// cylinder's y axis.  The y coordinate in the noise map represents the
    ///// height above the x-z plane.
    /////
    ///// The application must provide the lower and upper angle bounds of the
    ///// noise map, in degrees, and the lower and upper height bounds of the
    ///// noise map, in units.
    ////class NoiseMapBuilderCylinder: public NoiseMapBuilder
    ////{

    //// public:

    ////   /// Constructor.
    ////   NoiseMapBuilderCylinder ();

    ////   virtual void Build ();

    ////   /// Returns the lower angle boundary of the cylindrical noise map.
    ////   ///
    ////   /// @returns The lower angle boundary of the noise map, in degrees.
    ////   double GetLowerAngleBound () const
    ////   {
    ////     return this.lowerAngleBound;
    ////   }

    ////   /// Returns the lower height boundary of the cylindrical noise map.
    ////   ///
    ////   /// @returns The lower height boundary of the noise map, in units.
    ////   ///
    ////   /// One unit is equal to the radius of the cylinder.
    ////   double GetLowerHeightBound () const
    ////   {
    ////     return this.lowerHeightBound;
    ////   }

    ////   /// Returns the upper angle boundary of the cylindrical noise map.
    ////   ///
    ////   /// @returns The upper angle boundary of the noise map, in degrees.
    ////   double GetUpperAngleBound () const
    ////   {
    ////     return this.upperAngleBound;
    ////   }

    ////   /// Returns the upper height boundary of the cylindrical noise map.
    ////   ///
    ////   /// @returns The upper height boundary of the noise map, in units.
    ////   ///
    ////   /// One unit is equal to the radius of the cylinder.
    ////   double GetUpperHeightBound () const
    ////   {
    ////     return this.upperHeightBound;
    ////   }

    ////   /// Sets the coordinate boundaries of the noise map.
    ////   ///
    ////   /// @param lowerAngleBound The lower angle boundary of the noise map,
    ////   /// in degrees.
    ////   /// @param upperAngleBound The upper angle boundary of the noise map,
    ////   /// in degrees.
    ////   /// @param lowerHeightBound The lower height boundary of the noise
    ////   /// map, in units.
    ////   /// @param upperHeightBound The upper height boundary of the noise
    ////   /// map, in units.
    ////   ///
    ////   /// @pre The lower angle boundary is less than the upper angle
    ////   /// boundary.
    ////   /// @pre The lower height boundary is less than the upper height
    ////   /// boundary.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   ///
    ////   /// One unit is equal to the radius of the cylinder.
    ////   void SetBounds (double lowerAngleBound, double upperAngleBound,
    ////     double lowerHeightBound, double upperHeightBound)
    ////   {
    ////     if (lowerAngleBound >= upperAngleBound
    ////       || lowerHeightBound >= upperHeightBound) {
    ////       throw noise::ExceptionInvalidParam ();
    ////     }

    ////     this.lowerAngleBound  = lowerAngleBound ;
    ////     this.upperAngleBound  = upperAngleBound ;
    ////     this.lowerHeightBound = lowerHeightBound;
    ////     this.upperHeightBound = upperHeightBound;
    ////   }

    //// private:

    ////   /// Lower angle boundary of the cylindrical noise map, in degrees.
    ////   double this.lowerAngleBound;

    ////   /// Lower height boundary of the cylindrical noise map, in units.
    ////   double this.lowerHeightBound;

    ////   /// Upper angle boundary of the cylindrical noise map, in degrees.
    ////   double this.upperAngleBound;

    ////   /// Upper height boundary of the cylindrical noise map, in units.
    ////   double this.upperHeightBound;

    ////};

    ///// Builds a planar noise map.
    /////
    ///// This class builds a noise map by filling it with coherent-noise values
    ///// generated from the surface of a plane.
    /////
    ///// This class describes these input values using (x, z) coordinates.
    ///// Their y coordinates are always 0.0.
    /////
    ///// The application must provide the lower and upper x coordinate bounds
    ///// of the noise map, in units, and the lower and upper z coordinate
    ///// bounds of the noise map, in units.
    /////
    ///// To make a tileable noise map with no seams at the edges, call the
    ///// EnableSeamless() method.
    ////class NoiseMapBuilderPlane: public NoiseMapBuilder
    ////{

    //// public:

    ////   /// Constructor.
    ////   NoiseMapBuilderPlane ();

    ////   virtual void Build ();

    ////   /// Enables or disables seamless tiling.
    ////   ///
    ////   /// @param enable A flag that enables or disables seamless tiling.
    ////   ///
    ////   /// Enabling seamless tiling builds a noise map with no seams at the
    ////   /// edges.  This allows the noise map to be tileable.
    ////   void EnableSeamless (bool enable = true)
    ////   {
    ////     this.isSeamlessEnabled = enable;
    ////   }

    ////   /// Returns the lower x boundary of the planar noise map.
    ////   ///
    ////   /// @returns The lower x boundary of the planar noise map, in units.
    ////   double GetLowerXBound () const
    ////   {
    ////     return this.lowerXBound;
    ////   }

    ////   /// Returns the lower z boundary of the planar noise map.
    ////   ///
    ////   /// @returns The lower z boundary of the noise map, in units.
    ////   double GetLowerZBound () const
    ////   {
    ////     return this.lowerZBound;
    ////   }

    ////   /// Returns the upper x boundary of the planar noise map.
    ////   ///
    ////   /// @returns The upper x boundary of the noise map, in units.
    ////   double GetUpperXBound () const
    ////   {
    ////     return this.upperXBound;
    ////   }

    ////   /// Returns the upper z boundary of the planar noise map.
    ////   ///
    ////   /// @returns The upper z boundary of the noise map, in units.
    ////   double GetUpperZBound () const
    ////   {
    ////     return this.upperZBound;
    ////   }

    ////   /// Determines if seamless tiling is enabled.
    ////   ///
    ////   /// @returns
    ////   /// - @a true if seamless tiling is enabled.
    ////   /// - @a false if seamless tiling is disabled.
    ////   ///
    ////   /// Enabling seamless tiling builds a noise map with no seams at the
    ////   /// edges.  This allows the noise map to be tileable.
    ////   bool IsSeamlessEnabled () const
    ////   {
    ////     return this.isSeamlessEnabled;
    ////   }

    ////   /// Sets the boundaries of the planar noise map.
    ////   ///
    ////   /// @param lowerXBound The lower x boundary of the noise map, in
    ////   /// units.
    ////   /// @param upperXBound The upper x boundary of the noise map, in
    ////   /// units.
    ////   /// @param lowerZBound The lower z boundary of the noise map, in
    ////   /// units.
    ////   /// @param upperZBound The upper z boundary of the noise map, in
    ////   /// units.
    ////   ///
    ////   /// @pre The lower x boundary is less than the upper x boundary.
    ////   /// @pre The lower z boundary is less than the upper z boundary.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   void SetBounds (double lowerXBound, double upperXBound,
    ////     double lowerZBound, double upperZBound)
    ////   {
    ////     if (lowerXBound >= upperXBound
    ////       || lowerZBound >= upperZBound) {
    ////       throw noise::ExceptionInvalidParam ();
    ////     }

    ////     this.lowerXBound = lowerXBound;
    ////     this.upperXBound = upperXBound;
    ////     this.lowerZBound = lowerZBound;
    ////     this.upperZBound = upperZBound;
    ////   }

    //// private:

    ////   /// A flag specifying whether seamless tiling is enabled.
    ////   bool this.isSeamlessEnabled;

    ////   /// Lower x boundary of the planar noise map, in units.
    ////   double this.lowerXBound;

    ////   /// Lower z boundary of the planar noise map, in units.
    ////   double this.lowerZBound;

    ////   /// Upper x boundary of the planar noise map, in units.
    ////   double this.upperXBound;

    ////   /// Upper z boundary of the planar noise map, in units.
    ////   double this.upperZBound;

    ////};


    ///// Builds a spherical noise map.
    /////
    ///// This class builds a noise map by filling it with coherent-noise values
    ///// generated from the surface of a sphere.
    /////
    ///// This class describes these input values using a (latitude, longitude)
    ///// coordinate system.  After generating the coherent-noise value from the
    ///// input value, it then "flattens" these coordinates onto a plane so that
    ///// it can write the values into a two-dimensional noise map.
    /////
    ///// The sphere model has a radius of 1.0 unit.  Its center is at the
    ///// origin.
    /////
    ///// The x coordinate in the noise map represents the longitude.  The y
    ///// coordinate in the noise map represents the latitude.  
    /////
    ///// The application must provide the southern, northern, western, and
    ///// eastern bounds of the noise map, in degrees.
    ////class NoiseMapBuilderSphere: public NoiseMapBuilder
    ////{

    //// public:

    ////   /// Constructor.
    ////   NoiseMapBuilderSphere ();

    ////   virtual void Build ();

    ////   /// Returns the eastern boundary of the spherical noise map.
    ////   ///
    ////   /// @returns The eastern boundary of the noise map, in degrees.
    ////   double GetEastLonBound () const
    ////   {
    ////     return this.eastLonBound;
    ////   }

    ////   /// Returns the northern boundary of the spherical noise map
    ////   ///
    ////   /// @returns The northern boundary of the noise map, in degrees.
    ////   double GetNorthLatBound () const
    ////   {
    ////     return this.northLatBound;
    ////   }

    ////   /// Returns the southern boundary of the spherical noise map
    ////   ///
    ////   /// @returns The southern boundary of the noise map, in degrees.
    ////   double GetSouthLatBound () const
    ////   {
    ////     return this.southLatBound;
    ////   }

    ////   /// Returns the western boundary of the spherical noise map
    ////   ///
    ////   /// @returns The western boundary of the noise map, in degrees.
    ////   double GetWestLonBound () const
    ////   {
    ////     return this.westLonBound;
    ////   }

    ////   /// Sets the coordinate boundaries of the noise map.
    ////   ///
    ////   /// @param southLatBound The southern boundary of the noise map, in
    ////   /// degrees.
    ////   /// @param northLatBound The northern boundary of the noise map, in
    ////   /// degrees.
    ////   /// @param westLonBound The western boundary of the noise map, in
    ////   /// degrees.
    ////   /// @param eastLonBound The eastern boundary of the noise map, in
    ////   /// degrees.
    ////   ///
    ////   /// @pre The southern boundary is less than the northern boundary.
    ////   /// @pre The western boundary is less than the eastern boundary.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   void SetBounds (double southLatBound, double northLatBound,
    ////     double westLonBound, double eastLonBound)
    ////   {
    ////     if (southLatBound >= northLatBound
    ////       || westLonBound >= eastLonBound) {
    ////       throw noise::ExceptionInvalidParam ();
    ////     }

    ////     this.southLatBound = southLatBound;
    ////     this.northLatBound = northLatBound;
    ////     this.westLonBound  = westLonBound ;
    ////     this.eastLonBound  = eastLonBound ;
    ////   }

    //// private:

    ////   /// Eastern boundary of the spherical noise map, in degrees.
    ////   double this.eastLonBound;

    ////   /// Northern boundary of the spherical noise map, in degrees.
    ////   double this.northLatBound;

    ////   /// Southern boundary of the spherical noise map, in degrees.
    ////   double this.southLatBound;

    ////   /// Western boundary of the spherical noise map, in degrees.
    ////   double this.westLonBound;

    ////};

    ///// Renders an image from a noise map.
    /////
    ///// This class renders an image given the contents of a noise-map object.
    /////
    ///// An application can configure the output of the image in three ways:
    ///// - Specify the color gradient.
    ///// - Specify the light source parameters.
    ///// - Specify the background image.
    /////
    ///// <b>Specify the color gradient</b>
    /////
    ///// This class uses a color gradient to calculate the color for each pixel
    ///// in the destination image according to the value from the corresponding
    ///// position in the noise map.
    /////
    ///// A color gradient is a list of gradually-changing colors.  A color
    ///// gradient is defined by a list of <i>gradient points</i>.  Each
    ///// gradient point has a position and a color.  In a color gradient, the
    ///// colors between two adjacent gradient points are linearly interpolated.
    /////
    ///// For example, suppose this class contains the following color gradient:
    /////
    ///// - -1.0 maps to dark blue.
    ///// - -0.2 maps to light blue.
    ///// - -0.1 maps to tan.
    ///// - 0.0 maps to green.
    ///// - 1.0 maps to white.
    /////
    ///// The value 0.5 maps to a greenish-white color because 0.5 is halfway
    ///// between 0.0 (mapped to green) and 1.0 (mapped to white).
    /////
    ///// The value -0.6 maps to a medium blue color because -0.6 is halfway
    ///// between -1.0 (mapped to dark blue) and -0.2 (mapped to light blue).
    /////
    ///// The color gradient requires a minimum of two gradient points.
    /////
    ///// This class contains two pre-made gradients: a grayscale gradient and a
    ///// color gradient suitable for terrain.  To use these pre-made gradients,
    ///// call the BuildGrayscaleGradient() or BuildTerrainGradient() methods,
    ///// respectively.
    /////
    ///// @note The color value passed to AddGradientPoint() has an alpha
    ///// channel.  This alpha channel specifies how a pixel in the background
    ///// image (if specified) is blended with the calculated color.  If the
    ///// alpha value is high, this class weighs the blend towards the
    ///// calculated color, and if the alpha value is low, this class weighs the
    ///// blend towards the color from the corresponding pixel in the background
    ///// image.
    /////
    ///// <b>Specify the light source parameters</b>
    /////
    ///// This class contains a parallel light source that lights the image.  It
    ///// interprets the noise map as a bump map.
    /////
    ///// To enable or disable lighting, pass a bool value to the
    ///// EnableLight() method.
    /////
    ///// To set the position of the light source in the "sky", call the
    ///// SetLightAzimuth() and SetLightElev() methods.
    /////
    ///// To set the color of the light source, call the SetLightColor() method.
    /////
    ///// To set the intensity of the light source, call the SetLightIntensity()
    ///// method.  A good intensity value is 2.0, although that value tends to
    ///// "wash out" very light colors from the image.
    ///// 
    ///// To set the contrast amount between areas in light and areas in shadow,
    ///// call the SetLightContrast() method.  Determining the correct contrast
    ///// amount requires some trial and error, but if your application
    ///// interprets the noise map as a height map that has its elevation values
    ///// measured in meters and has a horizontal resolution of @a h meters, a
    ///// good contrast amount to use is (1.0 / @a h).
    ///// 
    ///// <b>Specify the background image</b>
    /////
    ///// To specify a background image, pass an Image object to the
    ///// SetBackgroundImage() method.
    /////
    ///// This class determines the color of a pixel in the destination image by
    ///// blending the calculated color with the color of the corresponding
    ///// pixel from the background image.
    /////
    ///// The blend amount is determined by the alpha of the calculated color.
    ///// If the alpha value is high, this class weighs the blend towards the
    ///// calculated color, and if the alpha value is low, this class weighs the
    ///// blend towards the color from the corresponding pixel in the background
    ///// image.
    /////
    ///// <b>Rendering the image</b>
    /////
    ///// To render the image, perform the following steps:
    ///// - Pass a NoiseMap object to the SetSourceNoiseMap() method.
    ///// - Pass an Image object to the SetDestImage() method.
    ///// - Pass an Image object to the SetBackgroundImage() method (optional)
    ///// - Call the Render() method.
    ////class RendererImage
    ////{

    //// public:

    ////   /// Constructor.
    ////   RendererImage ();

    ////   /// Adds a gradient point to this gradient object.
    ////   ///
    ////   /// @param gradientPos The position of this gradient point.
    ////   /// @param gradientColor The color of this gradient point.
    ////   ///
    ////   /// @pre No two gradient points have the same position.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   ///
    ////   /// This object uses a color gradient to calculate the color for each
    ////   /// pixel in the destination image according to the value from the
    ////   /// corresponding position in the noise map.
    ////   ///
    ////   /// The gradient requires a minimum of two gradient points.
    ////   ///
    ////   /// The specified color value passed to this method has an alpha
    ////   /// channel.  This alpha channel specifies how a pixel in the
    ////   /// background image (if specified) is blended with the calculated
    ////   /// color.  If the alpha value is high, this object weighs the blend
    ////   /// towards the calculated color, and if the alpha value is low, this
    ////   /// object weighs the blend towards the color from the corresponding
    ////   /// pixel in the background image.
    ////   void AddGradientPoint (double gradientPos,
    ////     const Color& gradientColor);

    ////   /// Builds a grayscale gradient.
    ////   ///
    ////   /// @post The original gradient is cleared and a grayscale gradient is
    ////   /// created.
    ////   ///
    ////   /// This color gradient contains the following gradient points:
    ////   /// - -1.0 maps to black
    ////   /// - 1.0 maps to white
    ////   void BuildGrayscaleGradient ();

    ////   /// Builds a color gradient suitable for terrain.
    ////   ///
    ////   /// @post The original gradient is cleared and a terrain gradient is
    ////   /// created.
    ////   ///
    ////   /// This gradient color at position 0.0 is the "sea level".  Above
    ////   /// that value, the gradient contains greens, browns, and whites.
    ////   /// Below that value, the gradient contains various shades of blue.
    ////   void BuildTerrainGradient ();

    ////   /// Clears the color gradient.
    ////   ///
    ////   /// Before calling the Render() method, the application must specify a
    ////   /// new color gradient with at least two gradient points.
    ////   void ClearGradient ();

    ////   /// Enables or disables the light source.
    ////   ///
    ////   /// @param enable A flag that enables or disables the light source.
    ////   ///
    ////   /// If the light source is enabled, this object will interpret the
    ////   /// noise map as a bump map.
    ////   void EnableLight (bool enable = true)
    ////   {
    ////     this.isLightEnabled = enable;
    ////   }

    ////   /// Enables or disables noise-map wrapping.
    ////   ///
    ////   /// @param enable A flag that enables or disables noise-map wrapping.
    ////   ///
    ////   /// This object requires five points (the initial point and its four
    ////   /// neighbors) to calculate light shading.  If wrapping is enabled,
    ////   /// and the initial point is on the edge of the noise map, the
    ////   /// appropriate neighbors that lie outside of the noise map will
    ////   /// "wrap" to the opposite side(s) of the noise map.  Otherwise, the
    ////   /// appropriate neighbors are cropped to the edge of the noise map.
    ////   ///
    ////   /// Enabling wrapping is useful when creating spherical renderings and
    ////   /// tileable textures.
    ////   void EnableWrap (bool enable = true)
    ////   {
    ////     this.isWrapEnabled = enable;
    ////   }

    ////   /// Returns the azimuth of the light source, in degrees.
    ////   ///
    ////   /// @returns The azimuth of the light source.
    ////   ///
    ////   /// The azimuth is the location of the light source around the
    ////   /// horizon:
    ////   /// - 0.0 degrees is east.
    ////   /// - 90.0 degrees is north.
    ////   /// - 180.0 degrees is west.
    ////   /// - 270.0 degrees is south.
    ////   double GetLightAzimuth () const
    ////   {
    ////     return this.lightAzimuth;
    ////   }

    ////   /// Returns the brightness of the light source.
    ////   ///
    ////   /// @returns The brightness of the light source.
    ////   double GetLightBrightness () const
    ////   {
    ////     return this.lightBrightness;
    ////   }

    ////   /// Returns the color of the light source.
    ////   ///
    ////   /// @returns The color of the light source.
    ////   Color GetLightColor () const
    ////   {
    ////     return this.lightColor;
    ////   }

    ////   /// Returns the contrast of the light source.
    ////   ///
    ////   /// @returns The contrast of the light source.
    ////   ///
    ////   /// The contrast specifies how sharp the boundary is between the
    ////   /// light-facing areas and the shadowed areas.
    ////   ///
    ////   /// The contrast determines the difference between areas in light and
    ////   /// areas in shadow.  Determining the correct contrast amount requires
    ////   /// some trial and error, but if your application interprets the noise
    ////   /// map as a height map that has a spatial resolution of @a h meters
    ////   /// and an elevation resolution of 1 meter, a good contrast amount to
    ////   /// use is (1.0 / @a h).
    ////   double GetLightContrast () const
    ////   {
    ////     return this.lightContrast;
    ////   }

    ////   /// Returns the elevation of the light source, in degrees.
    ////   ///
    ////   /// @returns The elevation of the light source.
    ////   ///
    ////   /// The elevation is the angle above the horizon:
    ////   /// - 0 degrees is on the horizon.
    ////   /// - 90 degrees is straight up.
    ////   double GetLightElev () const
    ////   {
    ////     return this.lightElev;
    ////   }

    ////   /// Returns the intensity of the light source.
    ////   ///
    ////   /// @returns The intensity of the light source.
    ////   double GetLightIntensity () const
    ////   {
    ////     return this.lightIntensity;
    ////   }

    ////   /// Determines if the light source is enabled.
    ////   ///
    ////   /// @returns
    ////   /// - @a true if the light source is enabled.
    ////   /// - @a false if the light source is disabled.
    ////   bool IsLightEnabled () const
    ////   {
    ////     return this.isLightEnabled;
    ////   }

    ////   /// Determines if noise-map wrapping is enabled.
    ////   ///
    ////   /// @returns
    ////   /// - @a true if noise-map wrapping is enabled.
    ////   /// - @a false if noise-map wrapping is disabled.
    ////   ///
    ////   /// This object requires five points (the initial point and its four
    ////   /// neighbors) to calculate light shading.  If wrapping is enabled,
    ////   /// and the initial point is on the edge of the noise map, the
    ////   /// appropriate neighbors that lie outside of the noise map will
    ////   /// "wrap" to the opposite side(s) of the noise map.  Otherwise, the
    ////   /// appropriate neighbors are cropped to the edge of the noise map.
    ////   ///
    ////   /// Enabling wrapping is useful when creating spherical renderings and
    ////   /// tileable textures
    ////   bool IsWrapEnabled () const
    ////   {
    ////     return this.isWrapEnabled;
    ////   }

    ////   /// Renders the destination image using the contents of the source
    ////   /// noise map and an optional background image.
    ////   ///
    ////   /// @pre SetSourceNoiseMap() has been previously called.
    ////   /// @pre SetDestImage() has been previously called.
    ////   /// @pre There are at least two gradient points in the color gradient.
    ////   /// @pre No two gradient points have the same position.
    ////   /// @pre If a background image was specified, it has the exact same
    ////   /// size as the source height map.
    ////   ///
    ////   /// @post The original contents of the destination image is destroyed.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   ///
    ////   /// The background image and the destination image can safely refer to
    ////   /// the same image, although in this case, the destination image is
    ////   /// irretrievably blended into the background image.
    ////   void Render ();

    ////   /// Sets the background image.
    ////   ///
    ////   /// @param backgroundImage The background image.
    ////   ///
    ////   /// If a background image has been specified, the Render() method
    ////   /// blends the pixels from the background image onto the corresponding
    ////   /// pixels in the destination image.  The blending weights are
    ////   /// determined by the alpha channel in the pixels in the destination
    ////   /// image.
    ////   ///
    ////   /// The destination image must exist throughout the lifetime of this
    ////   /// object unless another image replaces that image.
    ////   void SetBackgroundImage (const Image& backgroundImage)
    ////   {
    ////     this.pBackgroundImage = &backgroundImage;
    ////   }

    ////   /// Sets the destination image.
    ////   ///
    ////   /// @param destImage The destination image.
    ////   ///
    ////   /// The destination image will contain the rendered image after a
    ////   /// successful call to the Render() method.
    ////   ///
    ////   /// The destination image must exist throughout the lifetime of this
    ////   /// object unless another image replaces that image.
    ////   void SetDestImage (Image& destImage)
    ////   {
    ////     this.pDestImage = &destImage;
    ////   }

    ////   /// Sets the azimuth of the light source, in degrees.
    ////   ///
    ////   /// @param lightAzimuth The azimuth of the light source.
    ////   ///
    ////   /// The azimuth is the location of the light source around the
    ////   /// horizon:
    ////   /// - 0.0 degrees is east.
    ////   /// - 90.0 degrees is north.
    ////   /// - 180.0 degrees is west.
    ////   /// - 270.0 degrees is south.
    ////   ///
    ////   /// Make sure the light source is enabled via a call to the
    ////   /// EnableLight() method before calling the Render() method.
    ////   void SetLightAzimuth (double lightAzimuth)
    ////   {
    ////     this.lightAzimuth = lightAzimuth;
    ////     this.recalcLightValues = true;
    ////   }

    ////   /// Sets the brightness of the light source.
    ////   ///
    ////   /// @param lightBrightness The brightness of the light source.
    ////   ///
    ////   /// Make sure the light source is enabled via a call to the
    ////   /// EnableLight() method before calling the Render() method.
    ////   void SetLightBrightness (double lightBrightness)
    ////   {
    ////     this.lightBrightness = lightBrightness;
    ////     this.recalcLightValues = true;
    ////   }

    ////   /// Sets the color of the light source.
    ////   ///
    ////   /// @param lightColor The light color.
    ////   ///
    ////   /// Make sure the light source is enabled via a call to the
    ////   /// EnableLight() method before calling the Render() method.
    ////   void SetLightColor (const Color& lightColor)
    ////   {
    ////     this.lightColor = lightColor;
    ////   }

    ////   /// Sets the contrast of the light source.
    ////   ///
    ////   /// @param lightContrast The contrast of the light source.
    ////   ///
    ////   /// @pre The specified light contrast is positive.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   ///
    ////   /// The contrast specifies how sharp the boundary is between the
    ////   /// light-facing areas and the shadowed areas.
    ////   ///
    ////   /// The contrast determines the difference between areas in light and
    ////   /// areas in shadow.  Determining the correct contrast amount requires
    ////   /// some trial and error, but if your application interprets the noise
    ////   /// map as a height map that has a spatial resolution of @a h meters
    ////   /// and an elevation resolution of 1 meter, a good contrast amount to
    ////   /// use is (1.0 / @a h).
    ////   ///
    ////   /// Make sure the light source is enabled via a call to the
    ////   /// EnableLight() method before calling the Render() method.
    ////   void SetLightContrast (double lightContrast)
    ////   {
    ////     if (lightContrast <= 0.0) {
    ////       throw noise::ExceptionInvalidParam ();
    ////     }

    ////     this.lightContrast = lightContrast;
    ////     this.recalcLightValues = true;
    ////   }

    ////   /// Sets the elevation of the light source, in degrees.
    ////   ///
    ////   /// @param lightElev The elevation of the light source.
    ////   ///
    ////   /// The elevation is the angle above the horizon:
    ////   /// - 0 degrees is on the horizon.
    ////   /// - 90 degrees is straight up.
    ////   ///
    ////   /// Make sure the light source is enabled via a call to the
    ////   /// EnableLight() method before calling the Render() method.
    ////   void SetLightElev (double lightElev)
    ////   {
    ////     this.lightElev = lightElev;
    ////     this.recalcLightValues = true;
    ////   }

    ////   /// Returns the intensity of the light source.
    ////   ///
    ////   /// @returns The intensity of the light source.
    ////   ///
    ////   /// A good value for intensity is 2.0.
    ////   ///
    ////   /// Make sure the light source is enabled via a call to the
    ////   /// EnableLight() method before calling the Render() method.
    ////   void SetLightIntensity (double lightIntensity)
    ////   {
    ////     if (lightIntensity < 0.0) {
    ////       throw noise::ExceptionInvalidParam ();
    ////     }

    ////     this.lightIntensity = lightIntensity;
    ////     this.recalcLightValues = true;
    ////   }

    ////   /// Sets the source noise map.
    ////   ///
    ////   /// @param sourceNoiseMap The source noise map.
    ////   ///
    ////   /// The destination image must exist throughout the lifetime of this
    ////   /// object unless another image replaces that image.
    ////   void SetSourceNoiseMap (const NoiseMap& sourceNoiseMap)
    ////   {
    ////     this.pSourceNoiseMap = &sourceNoiseMap;
    ////   }

    //// private:

    ////   /// Calculates the destination color.
    ////   ///
    ////   /// @param sourceColor The source color generated from the color
    ////   /// gradient.
    ////   /// @param backgroundColor The color from the background image at the
    ////   /// corresponding position.
    ////   /// @param lightValue The intensity of the light at that position.
    ////   ///
    ////   /// @returns The destination color.
    ////   Color CalcDestColor (const Color& sourceColor,
    ////     const Color& backgroundColor, double lightValue) const;

    ////   /// Calculates the intensity of the light given some elevation values.
    ////   ///
    ////   /// @param center Elevation of the center point.
    ////   /// @param left Elevation of the point directly left of the center
    ////   /// point.
    ////   /// @param right Elevation of the point directly right of the center
    ////   /// point.
    ////   /// @param down Elevation of the point directly below the center
    ////   /// point.
    ////   /// @param up Elevation of the point directly above the center point.
    ////   ///
    ////   /// These values come directly from the noise map.
    ////   double CalcLightIntensity (double center, double left, double right,
    ////     double down, double up) const;

    ////   /// The cosine of the azimuth of the light source.
    ////   mutable double this.cosAzimuth;

    ////   /// The cosine of the elevation of the light source.
    ////   mutable double this.cosElev;

    ////   /// The color gradient used to specify the image colors.
    ////   GradientColor this.gradient;

    ////   /// A flag specifying whether lighting is enabled.
    ////   bool this.isLightEnabled;

    ////   /// A flag specifying whether wrapping is enabled.
    ////   bool this.isWrapEnabled;

    ////   /// The azimuth of the light source, in degrees.
    ////   double this.lightAzimuth;

    ////   /// The brightness of the light source.
    ////   double this.lightBrightness;

    ////   /// The color of the light source.
    ////   Color this.lightColor;

    ////   /// The contrast between areas in light and areas in shadow.
    ////   double this.lightContrast;

    ////   /// The elevation of the light source, in degrees.
    ////   double this.lightElev;

    ////   /// The intensity of the light source.
    ////   double this.lightIntensity;

    ////   /// A pointer to the background image.
    ////   const Image* this.pBackgroundImage;

    ////   /// A pointer to the destination image.
    ////   Image* this.pDestImage;

    ////   /// A pointer to the source noise map.
    ////   const NoiseMap* this.pSourceNoiseMap;

    ////   /// Used by the CalcLightIntensity() method to recalculate the light
    ////   /// values only if the light parameters change.
    ////   ///
    ////   /// When the light parameters change, this value is set to True.  When
    ////   /// the CalcLightIntensity() method is called, this value is set to
    ////   /// false.
    ////   mutable bool this.recalcLightValues;

    ////   /// The sine of the azimuth of the light source.
    ////   mutable double this.sinAzimuth;

    ////   /// The sine of the elevation of the light source.
    ////   mutable double this.sinElev;

    ////};

    ///// Renders a normal map from a noise map.
    /////
    ///// This class renders an image containing the normal vectors from a noise
    ///// map object.  This image can then be used as a bump map for a 3D
    ///// application or game.
    /////
    ///// This class encodes the (x, y, z) components of the normal vector into
    ///// the (red, green, blue) channels of the image.  Like any 24-bit
    ///// true-color image, the channel values range from 0 to 255.  0
    ///// represents a normal coordinate of -1.0 and 255 represents a normal
    ///// coordinate of +1.0.
    /////
    ///// You should also specify the <i>bump height</i> before rendering the
    ///// normal map.  The bump height specifies the ratio of spatial resolution
    ///// to elevation resolution.  For example, if your noise map has a spatial
    ///// resolution of 30 meters and an elevation resolution of one meter, set
    ///// the bump height to 1.0 / 30.0.
    /////
    ///// <b>Rendering the normal map</b>
    /////
    ///// To render the image containing the normal map, perform the following
    ///// steps:
    ///// - Pass a NoiseMap object to the SetSourceNoiseMap() method.
    ///// - Pass an Image object to the SetDestImage() method.
    ///// - Call the Render() method.
    ////class RendererNormalMap
    ////{

    //// public:

    ////   /// Constructor.
    ////   RendererNormalMap ();

    ////   /// Enables or disables noise-map wrapping.
    ////   ///
    ////   /// @param enable A flag that enables or disables noise-map wrapping.
    ////   ///
    ////   /// This object requires three points (the initial point and the right
    ////   /// and up neighbors) to calculate the normal vector at that point.
    ////   /// If wrapping is/ enabled, and the initial point is on the edge of
    ////   /// the noise map, the appropriate neighbors that lie outside of the
    ////   /// noise map will "wrap" to the opposite side(s) of the noise map.
    ////   /// Otherwise, the appropriate neighbors are cropped to the edge of
    ////   /// the noise map.
    ////   ///
    ////   /// Enabling wrapping is useful when creating spherical and tileable
    ////   /// normal maps.
    ////   void EnableWrap (bool enable = true)
    ////   {
    ////     this.isWrapEnabled = enable;
    ////   }

    ////   /// Returns the bump height.
    ////   ///
    ////   /// @returns The bump height.
    ////   ///
    ////   /// The bump height specifies the ratio of spatial resolution to
    ////   /// elevation resolution.  For example, if your noise map has a
    ////   /// spatial resolution of 30 meters and an elevation resolution of one
    ////   /// meter, set the bump height to 1.0 / 30.0.
    ////   ///
    ////   /// The spatial resolution and elevation resolution are determined by
    ////   /// the application.
    ////   double GetBumpHeight () const
    ////   {
    ////     return this.bumpHeight;
    ////   }

    ////   /// Determines if noise-map wrapping is enabled.
    ////   ///
    ////   /// @returns
    ////   /// - @a true if noise-map wrapping is enabled.
    ////   /// - @a false if noise-map wrapping is disabled.
    ////   ///
    ////   /// This object requires three points (the initial point and the right
    ////   /// and up neighbors) to calculate the normal vector at that point.
    ////   /// If wrapping is/ enabled, and the initial point is on the edge of
    ////   /// the noise map, the appropriate neighbors that lie outside of the
    ////   /// noise map will "wrap" to the opposite side(s) of the noise map.
    ////   /// Otherwise, the appropriate neighbors are cropped to the edge of
    ////   /// the noise map.
    ////   ///
    ////   /// Enabling wrapping is useful when creating spherical and tileable
    ////   /// normal maps.
    ////   bool IsWrapEnabled () const
    ////   {
    ////     return this.isWrapEnabled;
    ////   }

    ////   /// Renders the noise map to the destination image.
    ////   ///
    ////   /// @pre SetSourceNoiseMap() has been previously called.
    ////   /// @pre SetDestImage() has been previously called.
    ////   ///
    ////   /// @post The original contents of the destination image is destroyed.
    ////   ///
    ////   /// @throw noise::ExceptionInvalidParam See the preconditions.
    ////   void Render ();

    ////   /// Sets the bump height.
    ////   ///
    ////   /// @param bumpHeight The bump height.
    ////   ///
    ////   /// The bump height specifies the ratio of spatial resolution to
    ////   /// elevation resolution.  For example, if your noise map has a
    ////   /// spatial resolution of 30 meters and an elevation resolution of one
    ////   /// meter, set the bump height to 1.0 / 30.0.
    ////   ///
    ////   /// The spatial resolution and elevation resolution are determined by
    ////   /// the application.
    ////   void SetBumpHeight (double bumpHeight)
    ////   {
    ////     this.bumpHeight = bumpHeight;
    ////   }

    ////   /// Sets the destination image.
    ////   ///
    ////   /// @param destImage The destination image.
    ////   ///
    ////   /// The destination image will contain the normal map after a
    ////   /// successful call to the Render() method.
    ////   ///
    ////   /// The destination image must exist throughout the lifetime of this
    ////   /// object unless another image replaces that image.
    ////   void SetDestImage (Image& destImage)
    ////   {
    ////     this.pDestImage = &destImage;
    ////   }

    ////   /// Sets the source noise map.
    ////   ///
    ////   /// @param sourceNoiseMap The source noise map.
    ////   ///
    ////   /// The destination image must exist throughout the lifetime of this
    ////   /// object unless another image replaces that image.
    ////   void SetSourceNoiseMap (const NoiseMap& sourceNoiseMap)
    ////   {
    ////     this.pSourceNoiseMap = &sourceNoiseMap;
    ////   }

    //// private:

    ////   /// Calculates the normal vector at a given point on the noise map.
    ////   ///
    ////   /// @param nc The height of the given point in the noise map.
    ////   /// @param nr The height of the left neighbor.
    ////   /// @param nu The height of the up neighbor.
    ////   /// @param bumpHeight The bump height.
    ////   ///
    ////   /// @returns The normal vector represented as a color.
    ////   ///
    ////   /// This method encodes the (x, y, z) components of the normal vector
    ////   /// into the (red, green, blue) channels of the returned color.  In
    ////   /// order to represent the vector as a color, each coordinate of the
    ////   /// normal is mapped from the -1.0 to 1.0 range to the 0 to 255 range.
    ////   ///
    ////   /// The bump height specifies the ratio of spatial resolution to
    ////   /// elevation resolution.  For example, if your noise map has a
    ////   /// spatial resolution of 30 meters and an elevation resolution of one
    ////   /// meter, set the bump height to 1.0 / 30.0.
    ////   /// 
    ////   /// The spatial resolution and elevation resolution are determined by
    ////   /// the application.
    ////   Color CalcNormalColor (double nc, double nr, double nu,
    ////     double bumpHeight) const;

    ////   /// The bump height for the normal map.
    ////   double this.bumpHeight;

    ////   /// A flag specifying whether wrapping is enabled.
    ////   bool this.isWrapEnabled;

    ////   /// A pointer to the destination image.
    ////   Image* this.pDestImage;

    ////   /// A pointer to the source noise map.
    ////   const NoiseMap* this.pSourceNoiseMap;

    ////};

}

